AmigaE course

Sebastian Rittau <Jolly_Roger@H-Raiser.Berlinet.de>

Introduction

Some of you might know AmigaE. It is a programming language for the Amiga. It is a mix between C, Pascal and has features from other programming languages like LISP. It has also an inline assembler which gives E additional power. But E is easy to understand and that's why it is the ideal language for beginners and advanced programmers. AmigaE is best at system programming.

This course should help beginners to learn E and also gives some hints for advanced programmers. You need at least AmigaE 2.1b (the last freeware version) and for the later parts AmigaE 3.1a (registered) for this course. Both versions should be available at the AmiNet (dev/e). Additionally you need at least Kickstart and Workbench 2.04 (V37).

>From AmigaE 3.0 on, a tutorial to E is included in the archive. It is another good source to learn E. But this course is more system programming oriented, that means, it will show you how to program a GUI (Graphical User Interface) and how to program a good system-conform program.

Installing

After dearchiving the archive in the directory of your choice, you should make a special Shell for AmigaE:

start your favourite text-editor (Ed, MEmacs, GoldEd, CED, ...) (if you use a wordprocessor you have to save the files as ASCII!)
load "S:Shell-Startup"
add the following lines (replace <e-dir> with the directory you installed E in):
cd <e-dir> path bin add; assign EModules: Modules;
save the file as S:E-Startup (not S:Shell-Startup!)
copy the file SYS:System/Shell.info to any directory and rename it to E-Shell.info
click on the new icon and choose Icons/Information... from the menu
search for the tooltype FROM=xyz and change it FROM=S:E-Startup if you can't find it, click on add and type in FROM=S:E-Startup and press return
click on save

Now you can start the e-shell by double-clicking on the new icon.

Okay now make a directory for the course: type in
makedir course cd course in the e-shell.

Compiling programs

To make a program you have to write it in a easy readable form in any ASCII-Editor. All commands have a name which explains their function:

PROC: short for Procedure
IF: if something is true
THEN: then do something
WriteF: Write a sentence; and so on...

But these form is not readable for the computer. (Try to load any program into a textviewer. You don't see PROCs and that stuff, you only see cryptic characters) That's why we must translate the easy readable text (called the sourcecode or only source) into a form which is easy readable for the computer (the program). We use the program ec which is in the bin sub-directory of the e-dir to "compile" (translate) the sourcecode into the program. Because ec "compiles" the program it is called "compiler".

All sourcecodes (the files which contains the for you readable sentences) must have the ending .e to let ec know that it is a source. To compile the program you have to type
ec <filename of the sourcecode> in the e-shell. The ready-to-run program will have the name of the sourcecode without the ending .e (i.e. myprog.e will become myprog and so on...)

Comments

Okay, before beginning with out first program, I want to explain you what comments are and what they are user for.

You can use comments in your sourcecode to explain the function of a program-part or to give additional information about the program. Comments are ignored by the compiler. You should use comments often to explain your program. After a few weeks you don't write on a program, you can easily forget which function did what. The same problem appears on big programs ("What was this $%"&§$" proc good for?").

Another purpose of comments is debugging (i.e. finding and deleting errors). You can easily declare the parts of the program you don't need as comments.

There are to ways to make a comment:

One way is to mark the beginning of the comment with /* and the end with */:

  /* This is a comment - it is ignored by the compiler */

These comments are nested, that means, that for every /* you write there must be a matching */:

  /* This is a /* nested */ comment */

but:

  /* This would give an /* error because there are too many /*s */

and:

  /* Here are too many */s */

These comments can have more than one line:

  /* This comment
     is longer
     than one line */

The second way to make comments need AmigaE 3.0 or above. You can declare the rest of a line as comment by using -> :

  -> This is a comment

  INC x  -> This too, but INC x is a command

PROCs

E-Programs are built of so-called procedures. Each procedure is a little program which does a special job: a procedure could do output on the screen, square a number, make a GUI, play a sound-routine, free all memory that was allocated by another procedure and so on. Every procedure can call another procedures.

To declare a procedure:

  PROC nameofproc()
  /* Here are your commands */
  ENDPROC

It is called like nameofproc()

PROC: declares that here a new procedure begins. PROC must be uppercase, because it is an keyword
nameofproc: you must give every procedure an unique name. The first character must be lowercase!
valid names: myProc, tHiSmYoWnPrOc
not allowed: MyProc, ThIsMyOwNpRoC
(): Every procedure can have parameters. These parameters must be enclosed by parantheses behind the name. (Parameters will be explained later) If a procedure has no parameters, the room between the parantheses remains empty
ENDPROC: ends a procedure. For every PROC there must be a matching ENDPROC
nameofproc: to call a procedure just type its name, followed by
(): Again the parameters must be enclosed by parantheses behind the name

PROC main()

The most important procedure is called main. Every program must have a procedure with this name. The procedure main is called automatically when the program is started. If the ENDPROC of the proc main is hit, the program quits.

Okay, let's write our first program:

open your favourite editor

type in the following program:

  /* My first E-program */
  PROC main()
  ENDPROC

save it as <e-dir>/course/firstprog.e
change to the e-shell and type ec firstprog to compile the program. If ec reports an error, check your code
if you now type dir there should be the following output:
```
  firstprog                           firstprog.e
```
start firstprog. It is the ready-to-run-program

Whats that? Nothing happens? Oh, well, we have a proc but we have no command in this proc. So read in the next chapter about a command which writes something on the Shell.

WriteF()

With the command WriteF() you can write a string on the current shell. (For advanced users to the stdout). If no current Shell is defined, WriteF() opens a new Shell. A string is a sentence that is stored somewhere in the memory.

Simple usage: WriteF(string)

WriteF: the command
(...): the parantheses close in the arguments for this command
string: at the moment, we only use one argument. It is the string we want to write to the Shell

Strings must be closed in by apostrophes: 'This is a string'

If you forget the apostrophes, the compiler will report an error.

Example: WriteF('Hello World!')
The sentence "Hello World!" would written on the Shell.

Okay, let's add a WriteF() to our little program: add the line

  WriteF('Hello World!')

to our program. Where do you have to put the line? Well, try it out, compile the program and if the compiler returns no errors, start it.

If you really don't know what to do, the program should now look like:

  /* My first E-program */

  PROC main()
    WriteF('Hello World!')
  ENDPROC

The indentation before the line WriteF(...) has not to be written. It is only there to make clear, what belongs to the proc main. You should use these indentations to make clear, which command-pairs belong together.

Examples: PROC-ENDPROC; WHILE-ENDWHILE; IF-ELSE-ELSEIF-ENDIF and so on.

If you have done it right, on the Shell there should be something like

  Hello World!5.Work:AmigaE/Course>

Hmmmmmm, the prompt follows immediatly after "Hello World!". That means that we have to include a linefeed (i.e. a character which begins a new line) after "Hello World!". But because a linefeed is an unprintable character, we have to use a controlcode. Controlcodes begin with a backslash ("\") followed by a character. The character "n" is used for a "newline" (i.e. a linefeed). That means that you must add "\n" at the end of the string: WriteF('Hello World!\n')

Save, compile and start the changed version. Well, now it should be correct... Wow, that is your first real program in E.

Again PROCs (Boring theory again :( )

Okay, let's write a program which uses different procs (You don't have to take over all comments to your own program, but you should take over the comments which explain the program):

  /* Not longer my first program
     This one should show you how to use different procs */

  /* Let's begin with the main-procedure
     Some people write the main-proc at the end of their programs, but I
     write them at the beginning */
  PROC main()
    WriteF('Before the first proc\n') /* Don't forget the newline (\n) */
    /* Let's call another procedure. The program goes on with firstproc */
    firstproc()
    WriteF('After the first and before the second proc\n')
    /* Now let's call the last proc */
    secondproc()
    WriteF('After the second proc\n')
  ENDPROC

  PROC firstproc()
    WriteF('Now the program is in the first proc\n')
  ENDPROC /* The program returns to the command it called */

  PROC secondproc() IS WriteF('Now the program is in the second proc\n')

Save, compile and run it.

The output should be:

  Before the first proc
  Now the program is in the first proc
  After the first and before the second proc
  Now the program is in the second proc
  After the second proc

Maybe you have noticed the line

  PROC secondproc() IS WriteF('Now the program is in the second proc\n')

Well, this is a oneline-procedure. You can use these procs if you only use one command. You don't have to write ENDPROC.

PROC: define that a proc begins
secondproc(): name and arguments
IS: keyword that this is a oneline-proc
WriteF(...): The command

Okay, what does our program do?

First it writes a sentence (Before the first proc)
Then it jumps into the procedure "firstproc"
There it writes another sentence
Now it returns to the commands after firstproc()
There it writes the third sentence
It jumps in another proc "secondproc"
The fourth sentence
An it returns again, now to WriteF('After the second proc')
There it writes the last sentence
At last, it quits

Now delete the line

  secondproc()

What should happen? Just try the program to know whether you guess was right.

Well, now let's give you another example of procs:

  /* Another proc-example */

  PROC main()
    firstproc()
    secondproc()
  ENDPROC

  PROC firstproc()
    secondproc()
  ENDPROC

  PROC secondproc()
    WriteF('This sentence should appear twice!\nIt is only written in the second proc')
  ENDPROC

Next chapter it becomes really interesting. We learn about variables. They are very powerfull. Every program needs them!

About the author

Well, I'm a student, which biggest hobby is my Amiga :). I bought my first Computer (an A500) about 6 years ago and was facinated. After a short time I began to write my first small programs in AmigaBasic (Microsoft-Crap). When I bought a modem, last year, I discovered AmigaE (V2.1b) and began to learn it. It was my first real programming-language and thatswhy I had big problems with the libraries and all that OS-stuff (I never had any book to programming on the Amiga). Well, actually I try to wriggle through Assembly.

On the computer, I mainly program and visit bbs'es, but I am also interested in much other things (like creating HTML-pages, though I have no WWW-Access). My other hobby is learning for the school (not a real hobby, but the only thing, I have time for).